home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / fortran / libry51.zip / LIBRY3.DOC < prev    next >
Text File  |  1989-11-10  |  17KB  |  398 lines
  1. .pa
  2.                         STRING AND BUFFER MANIPULATION
  3.  
  4. The purpose of these procedures is that FORTRAN is rather ill suited to string
  5. and  buffer  manipulation.   Most of the operations can be done in FORTRAN but
  6. are extremely slow in comparison.  Also there is the annoying practice of some
  7. compilers  (e.g.  HP's FTN7X) to use fixed length character variables.  All of
  8. these routines were written in assembler.
  9.  
  10.  
  11.               QUICK LIST OF STRING AND BUFFER MANIPULATION
  12.  
  13. CSET..... set all the characters in a string
  14. DEC0DE... decode an array of reals contained in a character string
  15. FOLD..... case fold a character (a-z folds to A-Z)
  16. FOLDS.... case fold a character string (a-z folds to A-Z)
  17. IAND..... logical and
  18. IOR...... logical or
  19. IXOR..... logical exclusive or
  20. ILB...... left byte
  21. IRB...... right byte
  22. ISERCH... search for a character in a string
  23. MATCH.... check two character strings for a match
  24. MOVEC.... move one character string into another
  25. MOVEI.... move one integer array into another
  26. NBUFC1... determine the nominal length of a character string
  27. SWAPC.... swap two character strings
  28. SWAPI.... swap two integer arrays
  29. SORTC.... sort a group of character strings
  30. SORTCI... sort a group of indexed character strings
  31. SORTD.... sort an array of double precision reals
  32. SORTDI... sort an array of indexed double precision reals
  33. SORTI.... sort an array of integers
  34. SORTII... sort an array of indexed integers
  35. SORTR.... sort an array of reals
  36. SORTRI... sort an array of indexed reals
  37. .pa
  38. NAME:     CSET
  39. PURPOSE:  set all the characters in a string equal to a specific
  40.           character (such as blanks)
  41. TYPE:     subroutine (far external)
  42. SYNTAX:   CALL CSET(CBUF,NBUF,' ')
  43. INPUT:    a CHARACTER*1 variable (here ' ')
  44.           NBUF (INTEGER*2) number of characters in the target string
  45. OUTPUT:   CBUF (CHARACTER*1 CBUF(NBUF) or CHARACTER*80 CBUF, NBUF=80)
  46.  
  47.  
  48. NAME:     DEC0DE (note the "0" (zero), do not use an "O" (oh))
  49. PURPOSE:  decode an array of reals contained in a character string
  50. TYPE:     subroutine (far external)
  51. SYNTAX:   CALL DEC0DE(CBUF,NBUF,NCOL,R,N,IER)
  52. INPUT:    CBUF (any character string like '123 34.E4 5*0 100')
  53.           NBUF (INTEGER*2) the number of characters in CBUF
  54.           N (INTEGER*2) number of elements in R
  55. NOTE:     if you set N to a negative number, then DEC0DE will return in its
  56.           place the +number of reals actually decoded (of course, don't
  57.           use a constant like "-3" for this!)
  58. OUTPUT:   NCOL (INTEGER*2) the column where decoding stopped
  59.           R (REAL*4) an array (may be only 1 element)
  60.           IER (INTEGER*2) error return indicator (IER=0 is normal)
  61. USE:      In case you haven't noticed, some misguided persons at DEC and
  62.           Microsoft forgot to include the capability of free-format
  63.           reads from a character string (some people call character
  64.           strings "internal files" - why, is a mystery to me). Of
  65.           course, this is the most OBVIOUS reason for reading something
  66.           from a character string... perhaps that's why they left it
  67.           out. Well, DEC0DE is just the fix.
  68.  
  69.           DEC0DE will return an error if the syntax is incorrect or if
  70.           the string is empty. You must have at least one number in the
  71.           string. Missing numbers at the trailing end of a string will
  72.           be set to zero (viz. if you try to read 6 numbers and there
  73.           are only 3, the last 3 will come back as zero).
  74.  
  75.           Some examples of free format reals are given below. Note that
  76.           you can use the "*" to repeat numbers. Commas are optional.
  77.  
  78.                100 1.234 .0000123,45E4, 3*53.123 5*-7 -12.345E-05
  79.  
  80.           DEC0DE is written in assembler and is actually faster than
  81.           Microsoft's or HP's equivalent.  HP's FORTRAN will actually
  82.           perform this operation.
  83.  
  84.           When I want to read integers from a character string I first
  85.           read reals, then apply the "NINT" function as below
  86.  
  87.                CALL DEC0DE(CBUF,6,NCOL,R,1,IER)
  88.                IF(IER.NE.0) GO TO 999
  89.                I=NINT(R)
  90.  
  91.           The NINT function performs the real>integer conversion that is
  92.           what you probably want: (nearest integer) rather than the INT
  93.           function (truncate to integer).
  94.  
  95.  
  96. NAME:     FOLD
  97. PURPOSE:  case fold a character (a-z folds to A-Z)
  98. TYPE:     CHARACTER*1 function (far external)
  99. SYNTAX:   C2=FOLD(C1)
  100. INPUT:    C1 (CHARACTER*1)
  101. OUTPUT:   C2 (CHARACTER*1)
  102.  
  103.  
  104. NAME:     FOLDS
  105. PURPOSE:  case fold a character string (a-z folds to A-Z)
  106. TYPE:     subroutine (far external)
  107. SYNTAX:   CALL FOLDS(CBUF,NBUF)
  108. INPUT:    CBUF (CHARACTER*1 CBUF(NBUF) or CHARACTER*80 CBUF, NBUF=80)
  109.           NBUF (INTEGER*2) number of characters in the string
  110. OUTPUT:   CBUF
  111.  
  112.  
  113. NAME:     ISERCH
  114. PURPOSE:  search for a character in a string
  115. TYPE:     INTEGER*2 function (far external)
  116. SYNTAX:   K=ISERCH('?','are you kidding?',NBUF)
  117. INPUT:    a CHARACTER*1 variable (here '?')
  118.           CBUF (CHARACTER*1 CBUF(NBUF) or CHARACTER*80 CBUF, NBUF=80)
  119.           NBUF (INTEGER*2) number of characters in the string
  120. OUTPUT:   K (INTEGER*2)
  121. NOTE:     0<=K<=NBUF (if found, I will be first occurrence, if not
  122.           found, K=0)
  123.  
  124.  
  125. NAME:     IAND/IOR/IXOR
  126. PURPOSE:  logical functions
  127. TYPE:     INTEGER*2 function (far external)
  128. SYNTAX:   I=IAND(J,K)  I=IOR(J,K)  I=IXOR(J,K)
  129. INPUT:    J,K INTEGER*2 variables
  130. OUTPUT:   I (INTEGER*2)
  131.  
  132.  
  133. NAME:     ILB/IRB
  134. PURPOSE:  integer>integer/character
  135. TYPE:     INTEGER*2 function (far external)
  136. SYNTAX:   I=ILB(J)  I=IRB(J)
  137. INPUT:    J INTEGER*2 character
  138. OUTPUT:   I (INTEGER*2)
  139. NOTE:     I=ILB(J) is the same as I=J/256
  140.           I=IRB(J) is the same as I=MOD(J,256)
  141.  
  142.  
  143. NAME:     MATCH
  144. PURPOSE:  check two character strings for a match
  145. TYPE:     LOGICAL*2 function (far external)
  146. SYNTAX:   IF(MATCH(CBUF,'STOP',4)) GO TO 999
  147. INPUT:    two character strings (may be CHARACTER*1 CBUF1(NBUF),
  148.           CBUF2(NBUF) or CHARACTER*4 CBUF1,CBUF2)
  149.           NBUF (INTEGER*2) number of characters in the strings
  150. OUTPUT:   .true./.false.
  151. NOTE:     the strings need not have the same length as long as they are
  152.           both at least NBUF in length (here NBUF=4)
  153.  
  154.           One annoying thing about FORTRAN is that it won't compare the
  155.           first 4 characters of a string read in as 4A1 with a string
  156.           of length 4 like 'STOP'. MATCH solves this problem.
  157.  
  158.  
  159. NAME:     MOVEC
  160. PURPOSE:  move one character string into another
  161. TYPE:     subroutine (far external)
  162. SYNTAX:   CALL MOVEC(CBUF1,CBUF2,NBUF) or CALL MOVEC(CBUF,'STOP',4)
  163. INPUT:    CBUF2 a character string (may be CHARACTER*1 CBUF2(NBUF) or
  164.           CHARACTER*4 CBUF2)
  165.           NBUF (INTEGER*2) number of characters in the strings
  166. OUTPUT:   CBUF1 a character string (may be CHARACTER*1 CBUF1(NBUF) or
  167.           CHARACTER*4 CBUF1)
  168. NOTE:     the strings need not have the same length as long as they are
  169.           both at least NBUF in length (here NBUF=4)
  170.  
  171.           One annoying thing about FORTRAN is that it won't equivalence
  172.           first 4 characters of a 4A1 string to a string of length 4
  173.           like 'STOP'. MOVEC solves this problem. It's also much faster.
  174.  
  175.  
  176. NAME:     MOVEI
  177. PURPOSE:  move one integer array into another
  178. TYPE:     subroutine (far external)
  179. SYNTAX:   CALL MOVEI(IBUF1,IBUF2,NBUF)
  180. INPUT:    IBUF2 (INTEGER*2) an array
  181.           NBUF (INTEGER*2) number of elements in the arrays
  182. OUTPUT:   IBUF1 (INTEGER*2) an array
  183. NOTE:     the strings need not have the same length as long as they are
  184.           both at least NBUF in length
  185.  
  186.           This is about seventeen times as fast as a FORTRAN "DO LOOP".
  187.  
  188.  
  189. NAME:     NBUFC1
  190. PURPOSE:  determine the nominal length of a character string excluding
  191.           trailing blanks
  192. TYPE:     INTEGER*2 function (far external)
  193. SYNTAX:   IF(NBUFC1(CBUF,80).EQ.0) STOP   or
  194.           L=NBUFC1(CBUF,NBUF)
  195. INPUT:    CBUF a character string (may be CHARACTER*1 CBUF(NBUF) or
  196.           CHARACTER*4 CBUF)
  197.           NBUF (INTEGER*2) total number of characters in the string
  198. OUTPUT:   L (INTEGER